\chapter{Forth Words}

\section{Stack Manipulation}

\begin{description}

\item[drop ( a -- )]

Drop top of stack.

\item[dup ( a -- a a )]

Duplicate top of stack.

\item[swap ( a b -- b a )]

Swap top stack elements.

\item[over ( a b -- a b a )]

Make a copy of the second item and push it on top.

\item[rot ( a b c -- b c a )]

Rotate the third item to the top.

\item[-rot ( a b c -- c a b )]

rot rot

\item[2drop ( a b -- )]

Drop two topmost stack elements.

\item[2dup ( a b -- a b a b )]

Duplicate two topmost stack elements.

\item[?dup ( a -- a a? )]

Dup a if a differs from 0.

\item[nip ( a b -- b )]

swap drop

\item[tuck ( a b -- b a b )]

dup -rot

\item[pick ( $x_u$ ... $x_1$ $x_0$ $u$ -- $x_u$ ... $x_1$ $x_0$ $x_u$ )]

Pick from stack element with depth u to top of stack.

\item[$>$r ( a -- )]

Move value from top of parameter stack to top of return stack. 

\item[r$>$ ( -- a )]

Move value from top of return stack to top of parameter stack. 

\item[r@ ( -- a )]

Copy value from top of return stack to top of parameter stack. 

\end{description}

\section{Utility}

\begin{description}
\item[. ( a -- )] Print top value of stack.
\item[.s] See stack contents.
\item[emit ( a -- )] Print top byte of stack as a PETSCII character.
\item[\#] Comment to end of line.
\item[(] Start multi-line comment.
\item[)] End multi-line comment.
\item[bl] Space character (value).
\item[space] Prints a space (\texttt{bl emit}).
\end{description}

\section{Mathematics}

These words assume that the lowest number is 0 and highest is FFFF.

\begin{description}
\item[1+ ( a -- b )] Increase top of stack value by 1.
\item[1- ( a -- b )] Decrease top of stack value by 1.
\item[2+ ( a -- b )] Increase top of stack value by 2.
\item[2* ( a -- b )] Fast multiply top of stack value by 2.
\item[2/ ( a -- b )] Fast divide top of stack value by 2.
\item[100/ ( a -- b )] Divides top of stack value by \$100.
\item[+! ( n a -- )] Add n to memory address a.
\item[+ ( a b -- c )] Add a and b.
\item[- ( a b -- c )] Subtract b from a.
\item[* ( a b -- c )] Multiply a with b.
\item[d* ( a b -- msw lsw )] 32-bit multiply a with b.
\item[um/mod ( msw lsw d -- r q )] Divide 32-bit number by d, giving remainder r and quotient q.
\item[/mod ( a b -- r q )] Divide a with b, giving remainder r and quotient q.
\item[/ ( a b -- q )] Divide a with b.
\item[mod ( a b -- r )] Remainder of a divided by b.
\item[*/ ( a b c -- q )] Multiply a with b, then divide by c, using a 32-bit intermediary.
\item[*/mod ( a b c -- r q )] Like */, but also keeping remainder r.
\item[$<$ ( a b -- c )] Is a less than b?  
\item[$>$ ( a b -- c )] Is a greater than b?  
\item[$>=$ ( a b -- c )] Is a greater than or equal to b?
\item[$<=$ ( a b -- c )] Is a less than or equal to b?
\item[lshift ( a b -- c )] Binary shift a left by b.
\item[rshift ( a b -- c )] Binary shift a right by b.
\item[base (value)] Numerical base.
\item[decimal] Sets base to 10.
\item[hex] Sets base to 16.

\end{description}

\section{Signed Mathematics}

These words treat numbers like they are signed, meaning that numbers 8000 - FFFF are negative
and 0 - 7FFF are positive. (E.g., FFFF means -1.)

\begin{description}
\item[0$<$ ( a -- b )] Is a negative?
\item[negate ( a -- b )] Negates a.
\item[abs ( a -- b )] Gives absolute value of a.
\item[s$<$ ( a b -- c )] Is a less than b? (Signed comparison.)
\item[s$>$ ( a b -- c )] Is a greater than b? (Signed comparison.)
\end{description}

\section{Logic}

\begin{description}
\item[0= ( a -- flag)] Is a equal to zero?
\item[0$<>$ ( a -- flag )] Is a not equal to 0?
\item[= ( a b -- flag )] Is a equal to b?
\item[$<>$ ( a b -- flag )] Does a differ from b?
\item[and ( a b -- c )] Binary and.  
\item[or ( a b -- c )] Binary or.  
\item[xor ( a b -- c )] Binary exclusive or.  
\item[invert ( a -- b )] Flip all bits of a.  
\end{description}

\section{Memory}

\begin{description}
\item[! ( value address -- )] Store 16-bit value at address.  
\item[@ ( address -- value )] Fetch 16-bit value from address.  
\item[c! ( value address -- )] Store 8-bit value at address.  
\item[c@ ( address -- value )] Fetch 8-bit value from address.
\item[fill ( byte addr len -- )] Fill range [addr, len + addr) with byte value.
\item[cmove ( src dst len -- )]
Copy len bytes from src to dst. The move begins with the contents of src and proceeds towards high memory.
\item[cmove$>$ ( src dst len -- )]
Byte-to-byte copy like \texttt{cmove}, but starts with address src + len - 1 and proceeds towards src.
\item[forget xxx] Forget Forth word \texttt{xxx} and everything defined after it.

\end{description}
\section{Compiling}

\begin{description}
\item[:] Start compiling Forth word at \texttt{here} position.
\item[;] End compiling.
\item[, ( n -- )] Write word on stack to \texttt{here} position and increase \texttt{here} by 2.
\item[c, ( n -- )] Write byte on stack to \texttt{here} position and increase \texttt{here} by 1.
\item[literal ( n -- )] Compile a value from the stack as a literal value.
\item[[char{]} c] Compile character \texttt{c} as a literal value.
\item[[ ( -- )] Leave compile mode. Execute the following words immediately instead of compiling them.
\item[{]} ( -- )] Return to compile mode.
\item[immed] Mark the word being compiled as immediate (i.e. inside colon definitions, it will be executed immediately instead of compiled).
\item[{[']} xxx] Compile the execution token of word \texttt{xxx} as a literal value instead of executing it. (This does not work if \texttt{xxx} is an immediate words.)
\item[[compile{]} xxx] Compile the execution token of immediate word \texttt{xxx} instead of executing it.
\item[header xxx] Create a dictionary header with name \texttt{xxx}. 
\item[create xxx/does$>$] Create a word creating word \texttt{xxx} with custom behavior
specified after does>. For further description, see "Starting Forth."

\end{description}

\section{Variables}

\subsection{Values}

Values are fast to read, slow to write. Use values for variables
that are rarely changed. 

\begin{description}
\item[1 value foo] Create value foo and set it to 1.
\item[foo] Fetch value of foo.
\item[0 to foo] Set foo to 0.
\end{description}

\subsection{Variables}

Variables are faster to write to than values.

\begin{description}
\item[variable bar] Define variable bar.
\item[bar @] Fetch value of bar.
\item[1 bar !] Set bar to 1.
\end{description}

\subsection{Arrays}

\begin{description}
\item[10 allot value foo] Allocate 10 bytes to array foo.
\item[1 foo 2 + !] Store 1 in position 2 of foo.
\item[foo dump] See contents of foo.
\end{description}

It is also possible to build arrays using \texttt{create}. The initialization is easier, but access is slightly different:

\begin{verbatim}
create 2powtable
1 c, 2 c, 4 c, 8 c,
10 c, 20 c, 40 c, 80 c,
: 2pow ( n -- 2**n ) ['] 2powtable + c@ ;
\end{verbatim}

\section{Control Flow}

Control functions only work in compile mode, not in interpreter.

\begin{description}
\item[if ... then]

condition IF true-part THEN rest

\item[if ... else ... then]

condition IF true-part ELSE false-part THEN rest

\item[do ... loop] Start a loop with index \texttt{i} and limit. Example:

\begin{verbatim}
: print0to7 8 0 do i . loop ;
\end{verbatim}

\item[do ... +loop] Start a loop with a custom increment. Example:

\begin{verbatim}
( prints odd numbers from 1 to n )
: printoddnumbers (n -- ) 1 do i . 2 +loop ;
\end{verbatim}

\item[i, j] Variables are to be used inside \texttt{do} .. \texttt{loop} constructs.
\texttt{i} gives inner loop index, \texttt{j} gives outer loop index.

\item[begin ... again]

Infinite loop.

\item[begin ... until]

BEGIN loop-part condition UNTIL.

Loop until condition is true.

\item[begin ... while ... repeat]

BEGIN condition WHILE loop-part REPEAT.

Repeat loop-part while condition is true.

\item[exit]

Exit function.

\item[recurse] Jump to the start of the word being compiled.

\item[case ... endcase, of ... endof] Switch statements.

\begin{verbatim}
: tellno ( n -- )
case
1 of ." one" endof
2 of ." two" endof
3 of ." three" endof
." other"
endcase
\end{verbatim}

\end{description}

\section{Input}

\begin{description}

\item[key ( -- n )] Reads a character from current input (can be keyboard, disk or RAM).

\item[word ( -- addr )] Reads a word from input and put the string address on the stack.

\item[interpret ( -- value )] Interprets a word from input and puts it on the stack.

\item[compile-ram (value)] Makes DurexForth interpret from RAM.
E.g. \texttt{c000 compile-ram !} will make DurexForth
interpret from \texttt{c000}. The string to interpret
must be terminated with the bytes \texttt{20 00}.

\end{description}

\section{Editing}

\begin{description}
\item[vi ( -- )]

Enter editor. If a buffer is already open, editor will pick up where it left.
Otherwise, an untitled buffer will be created.

\end{description}

\begin{description}
\item[vi ( filenameptr filenamelen -- )]

Edit a file. Try \texttt{s" ls" vi}.

\end{description}

\section{Strings}

\begin{description}
\item[.(]

Print a string. Example: \texttt{.( foo)}

\item[."]

Compile-time version of "\texttt{.(}". Example: \texttt{: foo ." bar" ;}

\item[s"] ( -- strptr strlen )

Define a string. Example: \texttt{s" foo"}. 

\item[tell] ( strptr strlen -- )

Prints a string.

\end{description}

\section{Vectored Execution}

\begin{description}
\item[' xxx ( -- addr )] Find execution token of word \texttt{xxx}.
\item[lit xxx ( -- addr )] Equal to \texttt{'} but used for clarity. Use \texttt{' lit , ,} to compile the (run-time) value on top of stack.
\item[execute ( xt -- )] Execute the execution token on top of stack.
\item[loc xxx ( -- addr )] Run-time only: Get adress of word xxx.
\item[$>$cfa ( addr -- xt )] Get execution token (a.k.a. code field adress) of word at adress \texttt{addr}.

Example: \texttt{' words execute} equals \texttt{loc words >cfa execute} equals \texttt{words}.
\end{description}


\section{Debugging}

Debugging words are loaded with \texttt{s" debug" load}.

\begin{description}
\item[words] List all defined words.
\item[size] \texttt{size foo} prints size of \texttt{foo}.
\item[dump ( n -- )] Memory dump starting at address n.
\item[n] Continue memory dump where last one stopped.
\item[see word] Decompile Forth word and print to screen. Try \texttt{see see}.
\end{description}

\section{System State}

\begin{description}

\item[latest (variable)] Position of latest defined word.

\item[here (variable)] Write position of the Forth compiler (usually first unused byte of memory). Many C64 assemblers refer to this as program counter or \texttt{*}.

\item[sp@ ( -- addr )] Address of stack top before \texttt{sp@} is executed.
\item[sp0 (value)] Address of stack bottom.

\end{description}


\section{Disk I/O}

\begin{description}
\item[load ( filenameptr filenamelength -- )] Load and execute/compile file.
\item[loadb ( filenameptr filenamelength dst -- )] Load binary block to dst.
\item[saveb ( start end filenameptr filenamelength -- )] Save binary block.
\item[scratch ( filenameptr filenamelength -- )] Scratch file.
\end{description}

\section{Kernel Calls}

Safe kernel calls may be done from Forth words using \texttt{jsr} ( addr -- ). The helper variables \texttt{ar}, \texttt{xr}, \texttt{yr} and \texttt{sr} can be used to set arguments and get results through the a, x, y and status registers.

Example: \texttt{key 0 ar ! ffd2 jsr} prints \texttt{0} on screen.
